home *** CD-ROM | disk | FTP | other *** search
PPPPMMMMLLLLCCCC((((1111)))) PPPPMMMMLLLLCCCC((((1111)))) NNNNAAAAMMMMEEEE ppppmmmmllllcccc - configure active Performance Co-Pilot pmlogger(s) interactively SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ppppmmmmllllcccc [----eeee] [----hhhh _h_o_s_t] [----iiii] [----nnnn _p_m_n_s_f_i_l_e] [----PPPP] [----pppp _p_o_r_t] [----ZZZZ _t_i_m_e_z_o_n_e] [----zzzz] [ppppiiiidddd] DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN ppppmmmmllllcccc may be used to change those metrics and instances which a ppppmmmmllllooooggggggggeeeerrrr(1) writes to a Performance Co-Pilot archive (see PPPPCCCCPPPPIIIInnnnttttrrrroooo(1)), the frequency with which the metrics are collected and whether the logging is mandatory, advisory, on or off. It also reports the current logging status of metrics and instances. ppppmmmmllllcccc may be used to control pmlogger instances on remote hosts as well as those on the local host. Normally ppppmmmmllllcccc operates on the distributed Performance Metrics Name Space (PMNS), however if the ----nnnn option is specified an alternative local PMNS is loaded from the file _p_m_n_s_f_i_l_e. If the ----PPPP option is specified, ppppmmmmllllcccc will attempt to start with a connection to the primary pmlogger on the local host. If the ----pppp option is specified, then ppppmmmmllllcccc will attempt to start with a connection to the pmlogger on this TCP/IP _p_o_r_t. Alternatively, if _p_i_d is specified, a connection to the pmlogger instance with that process id will be attempted on startup. The ----hhhh option may only be used if ----PPPP,,,, ----pppp _p_o_r_t or a _p_i_d is also specified. In that case ppppmmmmllllcccc will initially connect to the specified (remote) pmlogger instance on _h_o_s_t rather than the local host. If the connection to the specified pmlogger instance cannot be established, ppppmmmmllllcccc will start with no connection. These options typically allow the same file of ppppmmmmllllcccc commands to be directed to multiple pmlogger instances by varying the command line arguments. Note that ----PPPP, ----pppp _p_o_r_t, _p_i_d and ----hhhh are used only when making an initial connection to a pmlogger instance. They are not used as defaults if subsequent connections are made interactively (see the ccccoooonnnnnnnneeeecccctttt command below). By default, ppppmmmmllllcccc reports the time of day according to the local timezone on the system where ppppmmmmllllcccc is run. The ----ZZZZ option changes the timezone to _t_i_m_e_z_o_n_e in the format of the environment variable TTTTZZZZ as described in eeeennnnvvvviiiirrrroooonnnn(5). The ----zzzz option changes the timezone to the timezone of the pmlogger instance from which information is being obtained. Only one of ----zzzz or ----ZZZZ may be specified. If standard input is from a tty, ppppmmmmllllcccc is interactive, with prompts. The ----iiii flag may be used to force interactive behavior, and is typically used in conjunction with ----eeee to echo all command input on standard output. The following commands may be used: sssshhhhoooowwww [ llllooooggggggggeeeerrrrssss ] [ @@@@_h_o_s_t ] Displays the process identities of all pmlogger instances running on the local host (or _h_o_s_t, if specified). The primary pmlogger pid is parenthesized because it can be referred to as "primary" as well as PPPPaaaaggggeeee 1111 PPPPMMMMLLLLCCCC((((1111)))) PPPPMMMMLLLLCCCC((((1111)))) by its pid. ccccoooonnnnnnnneeeecccctttt _p_i_d [ @@@@_h_o_s_t ] ccccoooonnnnnnnneeeecccctttt pppprrrriiiimmmmaaaarrrryyyy [ @@@@_h_o_s_t ] Connects ppppmmmmllllcccc to the specified pmlogger process. Any existing connection to a pmlogger instance is closed first. Each pmlogger instance will accept at most one connection at a time, so if the connection is successfully established, your ppppmmmmllllcccc will be the only one controlling the pmlogger instance it is connected to. nnnneeeewwww vvvvoooolllluuuummmmeeee This command works only while a connection to a pmlogger instance is established. It tells the pmlogger to close the current volume of the log and open a new volume. Closed volumes may be archived, e.g. as part of a regular log management procedure to control the size of the physical log files. ssssttttaaaattttuuuussss This command works only while a connection to a pmlogger instance is established. It prints information about the state of the pmlogger instance and its associated log. ttttiiiimmmmeeeezzzzoooonnnneeee llllooooccccaaaallll | llllooooggggggggeeeerrrr | """"_t_i_m_e_z_o_n_e"""" This command sets the time zone used when times are printed. llllooooccccaaaallll means use the time zone of the machine that ppppmmmmllllcccc is running on. llllooooggggggggeeeerrrr means use the time zone of the machine where the pmlogger instance is running. Alternatively an explicit _t_i_m_e_z_o_n_e enclosed in quotes may be supplied (refer to TTTTZZZZ in eeeennnnvvvviiiirrrroooonnnn(5) for details). The default time zone is llllooooccccaaaallll unless one of the ----zzzz or ----ZZZZ options has been supplied on the command line. fffflllluuuusssshhhh This command works only while a connection to a pmlogger instance is established, and requests the pmlogger instance to flush to disk all buffers associated with the current archive. For old-timers, ssssyyyynnnncccc is a synonym for fffflllluuuusssshhhh. hhhheeeellllpppp Displays a summary of the available commands. hhhh and ???? are synonyms for hhhheeeellllpppp. qqqquuuuiiiitttt Exits from ppppmmmmllllcccc. The remaining commands query and change the logging state of metrics and instances. They will work only if ppppmmmmllllcccc has a connection to a pmlogger instance. Metrics may be specified as fully qualified names (e.g. hinv.ncpu) or subtrees of the PMNS (e.g. hinv) which are expanded to include all metrics in the subtree (e.g. hinv.ncpu, hinv.cpuclock, etc.). Lists of metrics may be specified by enclosing them in braces with spaces or a comma between metrics (e.g. {hinv.ncpu hinv.ndisk}). Subtrees of metrics may be included in such lists. PPPPaaaaggggeeee 2222 PPPPMMMMLLLLCCCC((((1111)))) PPPPMMMMLLLLCCCC((((1111)))) Each individual metric specification may be further qualified with a space or comma separated list of instances in square brackets (e.g. kernel.all.load["1 minute", "5 minute"]). External instance names or numeric internal instance identifiers or both may be used in the same list (e.g. sample.colour.[red,1,"blue"]). If an instance qualification is applied to a subtree of the PMNS all of the metrics in the subtree must have the same instance domain. Instance qualifications may not be applied to entire lists of metrics but may appear inside such lists. If no instances are specified for a metric, all instances are used. All instances means all instances available at the time the pmlogger instance in question fetches the metrics for logging. If an instance domain changes over time this is not always the same as the set of instances displayed by ppppmmmmllllcccc, which can only display the currently available instances. To prevent unintentional errors, only the instances that are currently available to ppppmmmmllllcccc may appear in instance specifications. qqqquuuueeeerrrryyyy _m_e_t_r_i_c_l_i_s_t The current logging state of each metric (and instances, where applicable) in _m_e_t_r_i_c_l_i_s_t is displayed. This includes the logging state (e.g. on, maybe, off) and the logging interval for each metric (and instance) requested. The following abbreviations pertaining to metrics (and instances) may appear in the output: aaaaddddvvvv, advisory; mmmmaaaannnndddd, mandatory; nnnnllll, not in the log; nnnnaaaa, in the log but not currently available from its Performance Metrics Domain Agent (PMDA). Where appropriate, an instance name will appear last on a line preceded by its numeric internal instance identifier. [ lllloooogggg ] mmmmaaaannnnddddaaaattttoooorrrryyyy oooonnnn _i_n_t_e_r_v_a_l _m_e_t_r_i_c_l_i_s_t This form of the lllloooogggg command turns on logging for the metrics (and any instances) in _m_e_t_r_i_c_l_i_s_t. _i_n_t_e_r_v_a_l specifies how often the specified metrics/instances should be logged. oooonnnncccceeee indicates that the metrics/instances should appear at most once in the log. More often one would use the optional keyword eeeevvvveeeerrrryyyy followed by a positive number and one of mmmmiiiilllllllliiiisssseeeeccccoooonnnndddd (or mmmmsssseeeecccc), sssseeeeccccoooonnnndddd (or sssseeeecccc), mmmmiiiinnnnuuuutttteeee (or mmmmiiiinnnn), hhhhoooouuuurrrr or their plurals. Note that the keyword ddddeeeeffffaaaauuuulllltttt which may be used for the default _i_n_t_e_r_v_a_l in a ppppmmmmllllooooggggggggeeeerrrr(1) configuration file cannot be used in ppppmmmmllllcccc. Internal limitations require the _i_n_t_e_r_v_a_l to be less than (approximately) 74 hours. An _i_n_t_e_r_v_a_l value of zero is a synonym for oooonnnncccceeee. [ lllloooogggg ] mmmmaaaannnnddddaaaattttoooorrrryyyy ooooffffffff _m_e_t_r_i_c_l_i_s_t This tells the pmlogger instance not to log any of the metrics/instances in _m_e_t_r_i_c_l_i_s_t. [ lllloooogggg ] mmmmaaaannnnddddaaaattttoooorrrryyyy mmmmaaaayyyybbbbeeee _m_e_t_r_i_c_l_i_s_t This tells the pmlogger instance to honor any subsequent advisory logging requests for the metrics/instances in _m_e_t_r_i_c_l_i_s_t. If the current logging state of the metrics/instances is mandatory (either on or off) the new state will be set to maybe (effectively advisory PPPPaaaaggggeeee 3333 PPPPMMMMLLLLCCCC((((1111)))) PPPPMMMMLLLLCCCC((((1111)))) off). If the current state of the metrics/instances is already advisory (either on or off) the state(s) for the metrics/instances will remain as they are. [ lllloooogggg ] aaaaddddvvvviiiissssoooorrrryyyy oooonnnn _i_n_t_e_r_v_a_l _m_e_t_r_i_c_l_i_s_t [ lllloooogggg ] aaaaddddvvvviiiissssoooorrrryyyy ooooffffffff _m_e_t_r_i_c_l_i_s_t Advisory logging is only applicable if the last logging state specified for a metric/instance was "mandatory maybe" (which permits subsequent advisory logging control) or if the logging state is already advisory. These two statements turn advisory logging on or off (respectively) for the specified metrics/instances. The interpretation for _i_n_t_e_r_v_a_l is as above for the mmmmaaaannnnddddaaaattttoooorrrryyyy case. There is no continuation character required for commands that span lines. The word aaaatttt may be used interchangeably with @@@@. A request to log all instances of a metric will supersede any prior request to log either all or specific instances of a metric (if the request specifies a permissible transition in the logging state). A request to log specific instances of a metric when all instances of a metric are already being logged is refused by ppppmmmmllllooooggggggggeeeerrrr. PPPPCCCCPPPP EEEENNNNVVVVIIIIRRRROOOONNNNMMMMEEEENNNNTTTT Environment variables with the prefix PPPPCCCCPPPP____ are used to parameterize the file and directory names used by PCP. On each installation, the file /_e_t_c/_p_c_p._c_o_n_f contains the local values for these variables. The $$$$PPPPCCCCPPPP____CCCCOOOONNNNFFFF variable may be used to specify an alternative configuration file, as described in ppppccccpppp....ccccoooonnnnffff(4). SSSSEEEEEEEE AAAALLLLSSSSOOOO PPPPCCCCPPPPIIIInnnnttttrrrroooo(1), ppppmmmmccccdddd(1), ppppmmmmdddduuuummmmpppplllloooogggg(1), ppppmmmmllllooooggggggggeeeerrrr(1), ppppccccpppp....ccccoooonnnnffff(4), ppppccccpppp....eeeennnnvvvv(4) and eeeennnnvvvviiiirrrroooonnnn(5). DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS Most error or warning messages are self-explanatory. A message of the form Warning: unable to change logging state for... followed by a list of metrics (and possibly instances) indicates that ppppmmmmllllooooggggggggeeeerrrr refused the request for the metrics (and instances) that appear. Any metrics (and instances) that were specified but do not appear in the message have had their logging state updated successfully (no news is good news). Usually this warning results from requesting advisory logging when a mandatory control is already in place, or requesting logging for specific instances when all instances are already being logged. CCCCAAAAVVVVEEEEAAAATTTT If all instances of a metric are being logged and a request is made to log specific instances of the metric with the same state and frequency, the request may appear to succeed, even though ppppmmmmllllooooggggggggeeeerrrr has refused the request. This is not normally a problem, as the required information PPPPaaaaggggeeee 4444 PPPPMMMMLLLLCCCC((((1111)))) PPPPMMMMLLLLCCCC((((1111)))) will still be placed into the log by ppppmmmmllllooooggggggggeeeerrrr. However in the case where the metric is to be logged once, the outcome is not what might be expected. When ppppmmmmllllooooggggggggeeeerrrr receives a request to log a metric once, it places the current value(s) of the metric into the log as soon as it can, regardless of whether the metric is already in the log. This may be used to force values into the log. When a request to log specific instances of a metric arrives and is refused because all instances of the metric are already being logged, ppppmmmmllllooooggggggggeeeerrrr does not place values for the instances requested into the log. It returns the current logging state for each instance requested to ppppmmmmllllcccc. The requested and returned states are identical, so ppppmmmmllllcccc doesn't raise an error as it should. To ensure that only certain instances of a metric are being logged, one should always turn off logging for all instances of the metric prior to turning on logging for the specific instances required. PPPPaaaaggggeeee 5555 
